<html>
<head>
<meta http-equiv="Pragma" content="no-cache"/>
<meta http-equiv="Cache-Control" content="no-cache"/>
<meta http-equiv="Expires" content="-1" />
<title>Web Services - Sample 08: Using the JavaScript API</title>

<style><!--
a{text-decoration:none;
  padding: 1px;
  background-color: #dddddd}
--></style>

<script src="json2.js"></script> 
<script src="pymol.js"></script>

<script type="text/javascript">

var pymol = new PyMOL(null, null, 'on'); // create PyMOL object with buffering enabled

var cmd = pymol.cmd; // assign a global symbol for the PyMOL cmd API

function demoLoop() {

    cmd.reinitialize();
    cmd.load("$PYMOL_PATH/test/dat/1tii.pdb");
    cmd.color("white")

    cmd.count_atoms()
    count = pymol.flush()

    for(var i=1;i<=count;i++) {
        cmd.color("auto","index "+i);
    }
    pymol.flush()
}
</script>

</head>
<body>

<h3>Web Services - Sample 08: Using the JavaScript API</h3>

<a href="javascript:void(0)" onclick="window.open('view-source:' + location.href)">view page source</a>

<a href="/apply/_quit">quit pymol</a>

(FireFox only: <a href="javascript:void(0)" onclick="window.open('view-source:' + location.href)">view page source</a>)

<p>As you saw in Sample 06, the PyMOL JavaScript API re-exposes
PyMOL's Python programming interface directly to the JavaScript layer
in an object-oriented way.  However, there are some performance issues
(and in some cases, reliability issues) associated with sending
hundreds or perhaps thousands of HTTP requests in a very short period
of time.</p>

<p>We have implemented a buffering system into the PyMOL JavaScript
API which enables many requests to be combined into a single compound
request, provided of course, that only one return value (the final
result value) is required by the client.</p>

<p>The API is used as before, except that we enable the buffering option 
by passing 'on' as the third argument of the constructor</p>

<pre>
var pymol = new PyMOL(null, null, 'on'); // create PyMOL object with buffering enabled

var cmd = pymol.cmd; // assign a global symbol for the PyMOL cmd API
</pre>

<p>The trick to using buffering in the same origin scenario is to remember two things:</p>
<ol>
<li>PyMOL API calls are not actually invoked until you call pymol.flush()</li>
<li>The value returned from the final invocation is the result from pymol.flush()</li>
</ol>

<table>
<tr>
<th align="left"><b>Python (inside PyMOL)</b></th>
<th width="50">&nbsp;</th>
<th align="left"><b>JavaScript (inside Browser)</b></th>
</tr>
<tr>
<td valign="top"><pre>
cmd.reinitialize()
cmd.load("$PYMOL_PATH/test/dat/1tii.pdb")
cmd.color("white")


count = cmd.count_atoms()

for i in range(1,count+1):
    cmd.color("auto","index "+str(i))
</td><td>&nbsp;</td>
<td valign="top"><pre>
cmd.reinitialize();
cmd.load("$PYMOL_PATH/test/dat/1tii.pdb");
cmd.color("white")

cmd.count_atoms()
count = pymol.flush()

for(var i=1;i<=count;i++) {
    cmd.color("auto","index "+i);
}
pymol.flush()
</pre>

<a href="javascript:void(0)" onClick="demoLoop()">Run this program</a>
</td>
</tr>
</table>

<p>Note that you can turn buffering on or off at any time with the
setBufferMode method of the pymol object:</p>
<pre>pymol.setBufferMode('off') // disables buffering

list = cmd.get_chains('1tii')  // immediate calls can now be made, with results returned

pymol.setBufferMode('on') // restores buffering (must call flush to force execution)

</pre>


</body>
</html>
